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ABSTRACT 


This  report  provides  computer  programmers  with  documentation  for  a 
machine- independent  scientific  and  engineering  data-handler.  The 
report  discusses  design  concepts,  subroutine  functions,  application 
commands,  error  messages,  program  conversion,  test  routines,  and  pro 
cedures  for  changing  the  data-handler.  The  data-handler  has  been 
designed  to  minimize  the  resources  required  for  its  conversion  and 
operation. 
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1  DESIGN  CONCEPTS 


Introduction 


This  data-handler  is  a  feasible  method  by  which  a  programmer  can 
create  data  structures  on  disk  without  knowing  record  sizes,  data 
locations,  etc.  This  direct  access  system  provides  in-core  data  han¬ 
dling  so  that  physical  disk  accesses  are  minimized. 

The  programs  consist  of  several  data  storage  and  retrieval  func¬ 
tions  and  a  variety  of  other  utilities  which  create  and  delete  files, 
inform  the  user  of  file  status,  and  establish  or  remove  access  res¬ 
trictions.  The  programs  are  written  mostly  in  ANSI  FORTRAN. 


Definitions 

DATA  SET:  a  named,  independently  accessible  collection  of  data  on  a 
direct  access  storage  device,  created  and  maintained  by  the  host 
operating  system;  called  a  file  by  some  hardware  manufacturers. 

PHYSICAL  RECORD:  a  physical  portion  of  a  data  set  usually  of  fixed 
length,  which  is  accessible  by  means  of  one  input/output  operation 
the  computing  system. 

FILE:  a  named,  logical  subdivision  of  a  data  set. 

LOGICAL  RECORD:  a  logical  portion  of  a  file  of  variable  length,  which 
is  accessible  through  one  application  of  the  data-handler;  usually 
referred  to  simply  as  "record." 

In  essence,  the  data-handler  maintairi:,  a  logical  structure  of 
named  files  composed  of  variable- length,  randomly  accessible  records 
by  manipulating  physical  records  in  one  or  more  data  sets* 

APPLICATION  PROGRAM:  The  set  of  subroutine  that  are  using  the 
OH  for  data  base  management. 
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Data  Storage  Modes 


Two  storage  modes  control  how  data  is  stored  in  the  physical 
records  on  disk:  CHAIN  and  PACK. 


In  CHAIN  mode,  the  data-hand11  store  with  each  logical  record 
the  record  identifiers  of  the  preceding  and  following  logical  records 
in  the  file.  The  logical  records  must  therefore  remain  in  the  order 
in  which  they  are  written.  Chain  pointers  are  available  to  the  pro¬ 
grammer  who  is  reading  or  updating  logical  records.  The  pointers  are 
always  updated  whenever  a  logical  record  is  added  or  lengthened. 

In  PACK  mode,  the  data-handler- routines  will  fill  physical 
records  to  capacity  and,  when  necessary,  segment  logical  records 
which  span  two  or  more  physical  records. 

CHAIN  and  PACK  modes  may  be  specified  independently  so  that  four 
combinations  of  options  are  available: 


0  -  neither  CHAIN  nor  PACK 

1  -  CHAIN  only 

2  -  PACK  only 

3  -  CHAIN  and  PACK 


The  DH  recognizes  only  the  first  definition  of  this  option.  Any 
redefinitions  are  ignored  by  the  DH. 

Data  Management  Implementation 

The  "data  handler"  (DH)  is  a  general-purpose,  direct-access  data 
management  system.  The  DH  appears  to  an  application  program  as  a  set 
of  subroutines.  The  DH  is  written  largely  in  ANS  FORTRAN.  The  DH  is 
designed  as  an  interface  between  an  application  program  and  FORTRAN 
direct-access  input/output  (I/O)  facilities  (Figure  1).  This  pro¬ 
vides  a  two-fold  advantage.  Direct-access  I/O  can  be  performed  (1) 
at  a  logical  level  and  (2)  in  a  machine- independent  manner. 

The  DH  deals  with  only  direct-access  data  sets  (Figure  2).  The 
contents  of  a  dataset  must  be  understood  from  three  different  view 
points: 

(1)  host  system 

(2)  data  handler 

(3)  application  program 

a.  Host  System.  Data  sets  consist  of  physical  records. 

b.  Data  Handler.  Data  sets  consist  of  files.  Files  consist  of 
physical  records.  Physical  records  may  also  be  referred  to  as 


blocks.  Blocks  (physical-  records)  are  composed  of  logical  record 
segments. 


c.  Application  Program.  Data  sets  consist  of  files.  Files 
consist  of  logical  records. 

Several  cross-relationships  should  be  noted: 

(1)  The  logical  record  of  the  application  program  may  actually 
be  stored  within  one  or  more  data  handler  logical  record  segments. 

(2)  A  data  handler  block  may  be  written  as  one  or  more  operat¬ 
ing  system  physical  records. 


Program  Variable  Naming  Conventions 

The  names  used  for  variables  within  the  data  handler  follow  the 
following  logical  order: 

(1)  All  variable  names  are  five  letters  in  length. 

(2)  The  first  letter  options  are: 

a.  K  for  contents  of 

b.  I  for  index  to 

c.  N  for  number  of 

(3)  The  second  and  third  letters  options  are: 

.a.  PR  for  physical  record 

b,  LR  for  logical  record 

c.  OS  for  data  set 

d.  OF  for  open  file 

e,  BT  for  block  table 

(4)  The  fourth  letter  options  are: 
a.  H  for  header 

(5)  The  fifth  letter  options  are: 


a.  S  for  status 

b.  P  for  previous 


c.  F  for  following 

d.  N  for  number 
Data  Set  Struatures 

The  first  two  blocks  of  a  direct-access  data  set  maintained  by 
the  DH  contain  three  independent,  special-purpose  LR  segments  (Figure 
3).  These  blocks  do  not  belong  to  any  file,  and  the  segments  are 
known  as  the  data  set  header  (DSHED),  the  file  directory  (FD),  and 
the  free  space  table  (FST).  The  DSHED  and  FD  are  contained  in  the 
first  block,  while  the  FST  is  contained  in  the  second. 

The  DSHED  contains  various  information  about  the  data  set  and 
host  computer  system  (F^igure  4).  See  the  discussion  of  data  set 
table  entryjjsiow^o^'the  meanings  of  KDSSU,  KDSPR,  KDSBI,  KDSFS,  and 
KDSFD.  See  Table  |  for  the  meanings  of  NBSGN,  NBBLK,  DHFLG, 

0PSYS(2),  and  DHVEk.  The  time  is  given  in  the  form  hh:mm:ss,  and  the 
date  is  given  left- justified  and  blank -padded  in  the  form  dd-mmm-yy; 
they  are  the  time  and  date  when  the  data  set  was  initialized  by  the 
DH.  The  rest  of  the  elements  in  the  DSHED  are  the  same  as 
identically-named  elements  in  blank  C0MM0N. 

The  FD  contains  an  entry  for  each  file  that  is  contained  in  the 
data  set.'  An  FD  entry  is  identical  to  an  open  file  table  entry.  FD 
entries  are  numbered  consecutively  beginning  with  one. 

The  FST  is  a  bit  map;  each  bit  indicates  whether  (on)  or  not 
(off)  the  block  corresponding  to  that  bit  has  been  allocated  to  a  ^ 
file  in  the  data  set.  Both  the  FD  and  FST  are  extended  when  neces-^-  /- 
sary  to  additional  LR  segments.  -j  c ‘ 

The  j*emaining  blocks  are  used  to  store  data.  The  data  is  organ¬ 
ized  into  dynamic  collections  of  blocks  known  as  files.  One  block 
can  belong  to  only  one  file. 

3loc^<.  Stnictures 

Blocks  within  a  dataset  are  sequentially  numbered  starting  with 
one.  A  block  can  belong  to  only  one  file.  The  block  number  is  the 
sequential  number  assigned  to  a  block.  A  block  is  composed  of  three 
sections. 

/ 

The  first  three  SU's  in  each  block  are  known  as  the  physical 
record  (PR)  header  (figures).  The  first  SU  contains  the  contents  of 
the  physical  record  header  status  (KPRHS).  The  high-order  (left- 
hand)  half  6f  KPRHS  is  the  number  of  logical  record  segments  in  the 
block,  while  the  low-order  half  is  the  number  of  unused  SU's  at  the  ♦ 
end  of  the  block.  The  second  SU  KPRHP  is  the  block  number  of  the 
block  that  was  previously  written  for  the  file  to  which  this  block 
belongs;  it  is  zero  if  this  block  is  the  first  one  in  the  file.  The 
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Figure  4.  Data  Set  Header 


third  SU  KPRHF  is  the  block  number  of  the  block  that  was  subsequently 
written  or  is  next  to  be  added  to  this  file.  Hence,  the  blocks  that 
constitute  a  file  are  chained  together  in  both  directions. 

The  application  programs  logical  record  may  be  divided  by  the  DH 
into  segments  for  storage.  These  segments  are  known  as  logical 
record  segments.  The  block  will  contain  one  or  more  logical  record 
(LR)  segments.  There  are  three  reasons  why  an  LR  may  be  represented 
by  more  than  one  segment:  (1)  the  LR  is  too  long  to  fit  in  one 
block;  (2)  the  LR  is  too  long  to  fit  into  the  unused  portion  of  any 
block  belonging  to  the  file  for  which  this  LR  is  written,  and  the 
pack  option  is  in  effect  for  this  file;  (3)  the  LR  cannot  be  contigu¬ 
ously  extended  due  to  lack  of  space  in  the  block. 

The  remaining  portion  of  the  block  contains  unused  SU's. 

Logical  Record  Segment  Structure 

Associated  with  each  LR  segment  is  an  SU  quantity  known  as  the 
LR  segment  identifier  (ID).  The  high-order  quarter  of  this  quantity 
is  the  segment  number,  which  is  the  position  of  the  segment’ within 
the  block,  relative  to  the  beginning  of  the  block;  segments  are  num¬ 
bered  beginning  with  zero.  The  low-order  three-quarters  of  the  LR 
segment  ID  constitute  the  block  number.  If  the  LR  segment  is  the 
first  or  only  segment  of  the  LR,  then  the  LR  segment  ID  is  often 
called  simply  the  LR  ID. 

The  first  several  SU's  in  each  LR  segment  are  known  as  the  LR 
segment  header  (Figure  6).  The  extreme  high-order  portion  of  KLRHS 
contains  three  status  bits  known  as  the  continue,  segment,  and  delete 
bits,  whose  positions  are  given  by  the  CJJMMUN  variables  NBCUN,  NBSEG, 
and  NBDEL,  respectively  (Table  1).  Bits  within  an  SU  are  numbered 
from  right  to  left  beginning  with  zero.  The  continue  bit  indicates 
whether  (on)  or  not  (off)  this  LR  segment  is  continued  to  a  subse¬ 
quent  segment.  The  segment  bit  indicates  whether  (on)  or  not  (off) 
this  segment  is  continued  from  a  previous  segment.  The  deleteJ^ 
indicates,, whether  or  not  this  LR  has  been  deleted,..  The  four  low- 
order  bits  in  the  high-order' half  constitute  the  number  of  free  char¬ 
acters  in  the  last  SU.  The  low-order  half  of  KLRHS  is  the  number  of 
SU's  in  the  LR  (segment)  including  the  header.  The  segments  that 
represent  an  LR  are  chained  together  in  both  directions,  but  the  LR's 
that  constitute  a  file  are  chained  only  if  the  chain  option  is  in 
effect  for  the  file  (Figure  7). 

KLRHP  contains  the  following: 


No  Chain  Option 


(1)  If  this  LRS  is  the  first  one  in  the  file,  zero. 


Segment  Number 


Figure  6.  Logical  Record  Segment  Layout 


Figure  7.  Logical  Record  Segment  Chain 


TABLE  1 


FIXED  AREA 


Variable/  Position 
Array  in  COWiCN  Description 


Va  1  ue 


1.  SYSTEM  WIDE 


1 

2 

3 

4 


***  Machine  Characteristics  *** 


NBW 

5 

Number  of  bits*  per  word 

NCW 

6 

Number  characters  in  a  word 

NAW 

7 

Number  of  addresses  in  a  word 

NBC 

8 

Number  of  bits  per  character 

NCU 

9 

Number  of  characters  in  a 
“standard  unit"  (approximately 

32  bits  long) 

NBU 

10 

Number  of  bits  per  standard 
unit 

NAU 

11 

Number  of  addresses  in  a 
standard  unit 

NBU2 

12 

One-half  of  NBU 

NC2U 

13 

Number  of  characters  in  a  double 
precision  variable  (about  8-10  chars) 

RVRSE 

14 

Flag  telling  order  of  characters; 

0  •  left  to  right 

1  ■  right  to  left 

NWPSU 

15 

Number  of  real  words  per  standard 
unit: 

0  ■  two  SU's  per  real  (e.g.  IBM  1130) 

1  ■  one  SU  per  real  (e.g.  IBM  360) 

2  «  two  real ' s  per  SU 
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TABLE  1  (CONI' D) 


Variable/  Position 
Array  in  COMMON  Description 


Value 


LFIW 

16 

Number  of  bits  in  a  FORTRAN  integer 

LFIWU 

17 

Number  of  useable  bits  in  a  FORTRAN 
integer 

18 

19 

20 

21 

22 

23 

***  Standard  Devices  *** 

ICRO 

24 

Card  reader  logical  unit  number 

IPRT 

25 

Line  printer  logical  unit  number 

IPCH 

26 

Card  punch  logical  unit  number 

ITAP 

27 

Magnetic  tape  logical  unit  number 

ITRMI 

28 

Terminal  input  logical  unit  number 

ITRMO 

29 

Terminal  output  logical  unit  number 

JTRMI 

30 

Second  terminal  input  logical 
unit  number 

JTRMO 

31 

Second  terminal  output  logical 
unit  number 

IPLT 

32 

Plotter  logical  unit  number 

I6RAI 

33 

Interactive  graphics  input  logical 
unit 

IGRAC 

34 

Interactive  graphics  output  logical 
unit 

TABLE  1  (CCNT'O) 


Variable/ 

Array 

Position 
in  COMMON 

Description 

35 

36 

37 

***  Constants  and  Masks  *** 

TRU 

.38 

Value  of  logcial  true  (largest 
positive  integer) 

FALS 

■so 

ww 

Value  of  logical  false  (largest 
negative  integer) 

ZEROS 

40 

A  word  of  all  "zeros" 

ONES 

41 

A  word  of  all  "ones" 

FORMl 

42 

Token  format  mask  (1,2,1) 

F0RM2 

43 

« 

CDL  dictionary  format  mask  (2,2) 

FORMS 

44 

CDB  pointer  format  mask  (3,1) 

45 

46 

47 

48 

/ 

49 

***  Executive  Data  Area  *** 

SCA 

50 

Subscript  of  start  of  communications 
area  ("ITS) 

ATLID 

51 

LRID  of  active  task  list 

SCRFL 

52 

Name  of  executive  work  file 

SCRFL 

53 

Name  of  executive  work  file 
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1 
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TABLE  1  (CONT'O) 


I 


I 


Variable/ 

Array 

Position 
in  COMMON 

Description 

54 

***  Lexical  Analyzer  Data  Area  *** 

NXCHR 

55 

Next  character  in  input  buffer 

IDFT 

56 

Data  field  type 

I  STD 

57 

Start  of  data  field 

LSTR 

58 

Length  of  string  or  an  integer  value 

DCOM 

59 

Command  (up  to  8  characters)  or  a  ' 

DCOM 

60 

double  precision  value 

MLCA 

61 

Maximum  length  of  user  communications 
area  (for  referencing  in  a  CDB) 

SYOID 

62 

LRID  of  system  command  dictionary 

DICID 

63 

LRID  of  current  command  dictionary 

CDBNM 

64 

Name  of  current  CDB 

CDBNM 

65 

Name  of  current  CDB 

CDBID 

66 

LRID  of  current  CDB 

SYMID 

67 

LRID  of  current  symbol  table 

SVTID 

68 

LRID  of  current  standard  value  table 

NXELM 

■  69 

Pointer  to  next  CDB  element 

RELOC 

70 

Subsystem  common  relocation  factor 
(must  be  a  positive  number) 

CSTID 

71 

LRID  of  modifier  condition  stack 

WATID 

72 

LRID  of  ID  wait  list 

73 

74 
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Value 


TABLE  1  (CONI' D) 


Variable/ 

Array 

Position 
in  COMMON 

Description 

Value 

75 

2.  DATA 

HANDLER  INTERNAL  VARIABLE  AND  ARRAYS. 

IPOGL 

76 

Position  in  COMMON  of 
beginning  of  pool  area 

201 

IPLEN 

77 

Length  of  pool  area 

9800 

NBLMX 

78 

Maximum  length  of  a  block 

256 

NBSGN 

79 

Number  of  bits  in  a  segment 
number 

8 

NBBLK 

80 

Number  of  bits  in  a  block- 
number 

24 

ILLRH 

81 

Length  of  an  LR  (segment) 
header 

4 

ILRHS 

82 

■  Position  in  LR  (segment) 
header  of  KLRHS 

1 

ILRHN 

83 

Position  in  LR  (segment) 
header  of  KLRHN 

2 

ILRh,- 

84 

Position  in  LR  (segment) 
header  of  KLRHP 

3 

ILRHF 

85 

Position  in  LR  (segment 
header  of  KLRHF 

4 

ILPRH 

86 

Length  of  a  PR  header 

3 

IPP.MS 

87 

Position  in  PR  header  of 

KPRHS 

1 

IPRHP 

88 

Position  in  PR  header  of 

KPRHP 

2 

IPRHF 

89 

Position  in  PR  header  of 

KPRHF 

3 

IBTST 

90 

O'th  displacement  of  BT 

(computed) 

17 


TABLE  1  (CONT’D) 


Variable/ 

Array 

Position 
in  COMMON 

Description 

Val  ue 

NEBT 

91 

Number  of  BT  entries 

(computed) 

lELBT 

92 

Length  of  a  BT  entry 

273 

ILBTH 

93 

Length  of  a  BT  header 

17 

IBTNS 

94 

Position  in  BT  header  of 

KBTNS 

1 

IBTBL 

95 

Position  in  BT  header  of 

KBTBL 

2 

IBTQ 

96 

Position  in  BT  header  of 

KBTQ 

3 

IBTPP 

97 

Position  in  BT  header  of 

KBTPP 

4 

IBTL 

98 

Position  in  BT  header  of 

KBTL 

5 

IBTTR 

99 

Position  in  BT  header  of 

KBHR 

6 

IBTCN 

ICO 

Position  in  BT  header  of 

KBTCN 

7 

IBTDP 

101 

Position  in  BT  header  of 

KBTDP 

8 

IBTNC 

102 

Position  in  BT  header  of 

KBTNC 

9 

IBTSW 

103 

Position  in  BT  header  of 

KBTSW 

10 

IBTFN 

104 

Position  in  BT  header  of 

KBTFN 

11 

IBTFl 

105 

Position  in  BT  header  of 

KBTFI 

15 

IBTPI 

106 

Position  in  BT  header  of 

KBTPI 

16 

18 


TABLE  1  (CONI' D) 


Variable/ 

Array 

Position 
in  COMMON 

Descri ption 

Val  ue 

IBTLN 

107 

Position  in  BT  header  of 

KBTLN 

17 

IBTLG 

108 

O'th  displacement  of  BT 
entry  referenced  as  result 
of  most  recent  call  of  DKGET 

(variable*) 

IBTPQ 

109 

O'th  displacement  of  BT 
priority  queue 

(computed) 

IBTOP 

110 

Position  in  BT  of  entry 
with  highest  priority 

(variable**) 

IBTBT 

111 

Position  in  BT  of  entry 
with  lowest  priority) 

(variable*** 

I  OF  ST 

112 

O'th  displacement  of  OFT 

(computed) 

NEOFT 

113 

Number  of  OFT  entries 

125 

lELOF 

114 

Length  of  an  OFT  entry 

9 

ICFFN 

115 

Position  in  OFT  entry  of 

KOFFN 

5 

lOFFL 

116 

Position  in  OFT  entry  of 

KOFFL 

6 

lOFLL 

117 

Position  of  OFT  entry  of 

KOFNB 

7 

lOFNB 

118 

Position  in  OFT  entry  of 

KOFNB 

8 

lOFLB 

119 

Position  in  OFT  entry  of 

KOFLB 

8 

ICFFO 

120 

Position  in  OFT  entry  of 

KOFFD 

9 

IDSST 

121 

O'th  displacement  of  DST 

200 

I  ELDS 

122 

Length  of  a  DST  entry 

12 
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TABLE  1  (CCNT'D) 


Variable/ 

Array 

Position 
in  CO^^^<CN 

Description 

Val  ue 

IDSLU 

123 

Position  in  DST  entry  of 

KDSLU 

1 

IDSFN 

124 

Position  in  DST  entry  of 

KDSFN 

2 

IDSPR 

125 

Position  in  DST  entry  of 

KDSPR 

4 

IDSPE 

126 

Position  in  DST  entry  of 

KDSPB 

5 

IDSPL 

127 

Position  in  DST  entry  of 

DKSPL 

6 

• 

IDSFD 

128 

Position  in  DST  entry  of 

KDSFD 

8 

IDSFS 

129 

Position  in  DST  entry  of 

KDSFS 

9  • 

IDSSU 

130  : 

Position  in  DST  entry  of 

KDSSU 

7 

ILDSN 

121 

Length  of  a  data  set  name 

2 

0PSYS(2) 

132 

Name  of  host  operating 
system 

' IBK  OS 

DHVER 

134 

DH  version 

•VIF  ' 

DHFLG 

135 

DH  flag 

'DH  ' 

NBCON 

136 

Position  in  KLRHS  of 
continue  bit 

29 

NESEG 

137 

Position  in  KLRHS  of 
segment  bit 

30 

NBDEL 

138 

Position  in  KLRHS  of 
delete  bit 

21 

NBWIN 

129 

Position  in  KBTSW  of 
written-into  bit 

0 

20 


■.'W  nil 


TABLE  1  {CONI' D) 


a 


Variable/ 
j|  Array 

Position 
in  COMMON 

Description 

Value 

b’: 

NBRIT 

1 

140 

Position  in  KBTSW  of 
write-in-progress  bit 

1 

NBRED 

>  • 

141 

Position  in  KBTSW  of 
read-in-progress  bit 

2 

^  NBOPN 

1 

142 

Position  in  KDSLU  of 
open  bit 

16 

I:';  NBCLD 

143 

Position  in  KDSLU  of 
old  bit 

17 

^  NBSAV 

144 

Position  in  KDSLU  of 
save  bit 

18 

NBSHR 

145 

Position  in  KDLSU  of 
share  bit 

19 

NBCHN 

146 

Position  in.KOFFD  of 
chain  bit 

C 

NBPk 

147 

Position  in  KOFFD  of 
pack  bit 

1 

1  NBPRC 

148 

Position  in  KOFFD  of 
protect  bit 

4 

:•  NBNDS 

149 

Bit  position  in  KOFFD  of 
beginning  of  data  set  number 

8 

^  KO 

150 

Zero 

C 

K1 

151 

One 

1 

"  K2 

152 

Two 

2 

j  IDSBI 

153 

Position  in  DST  entry  of 

KDSBl 

10 

IDSWN 

154 

Position  in  DST  entry  of 

KDSWN 

11 

i 

155 

Position  in  DST  entry  of 

KDSWD 

12 
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TABLE  1  (CCNT'D) 


Variable/ 

Array 

Position 
in  COMMON 

Description 

Value 

HEDLR(4) 

156 

Work  area  for  an  LR 
(segment)  header 

(vari able) 

DST(12) 

156 

Work  area  for  a  DST  entry 

(variable) 

DATA (17) 

160 

Work  area  for  a  BT  heecer 

(variable) 

3. 

DATA  HANDLER  COMMUNICATIONS. 

STASK 

176 

Sending  task  name  (RSX-llD 
scratch  area) 

LCA 

177 

Length  of  user  communications  area 
transmitted  by  last/next  message  set 

TRACE 

178 

Executive  trace  switch:  each  bit, 

when  on,  indicates  a  type  of  tracing 
to  be  printed  on  unit  IPRT. 

Bit  (Value)  Item  Printed 
'T’  1  Digitize  expansions 

1  2  Tokens  created 

2  4  Macro  expansions 

3  8  Macro  argument 

Substitions 

4  16  Names  of  program.s/tasks 

executed 

5  32  Names  of  CDB's  called 

6  64  Statements  of  CDB's 

interpreted 

7  128  Common  values  modified 

8  256  Macro  processor  return 

information 

9  512  Command  dictionary  search 

information 

10  1024 

11  2048 

12  4096 

13  8192 

14  16384 

15  32768 


TABLE  1  (CCNT'D) 


Variable/  Position 
Array  in  COMMON  Description 


Val  ue 


EXSTl  179 


180 

PST  ID 

181 

TOR  ID 

•182 

TVLID 

182 

NXTKN 

184 

185 

INCMD 

186 

fiAXGP 

187 

Executive  status  switch  1:  Each 
bit,  when  on.  signifies  the  presence 
of  seme  exceptional  condition. 


Bit 

(Val ue; 

Meaning 

“(T 

1 

Return  to  executive 

1 

2 

ID  labels  required 

2 

4 

ID  wait  list  processing 

w 

8 

Inhibit  user  program 
execution  (system  control) 

4 

16 

Inhibit  user  program 
execution  (user  control) 

5 

32 

Next  record  continuation 
of  preceeding  command 

6 

64 

Repeat  tabular  processing 

7 

128 

End  of  file  on  input 

8 

256 

Input  error  occurred  (Cl) 

9 

512 

10 

1024 

User  program  signaled 
error 

11 

2048 

12 

4096 

Interactive  mode 

13 

8192 

14 

16384 

15 

32768 

LRID  of  prcgram/CDB  stack 
LRID  of  token  list 
LRID  cf  token  value  table 
Next  token  to  be  processed 


Logical  unit  number  from  which 
to  read  commands 

***  Data  Handler  Arguments  *** 

f'laximum  number  of  characters  per 
GET /PUT 
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TABLE  1  (CCNT'D) 


Variable/  Position 
Array  ■  in  COMMON  Description 


Value 


NDS 

188 

Data  set  number 

FILNM 

189 

File  name  (up  to  8  characters) 

FILNM 

190 

File  name  (up  to  8  characters) 

LULID 

191 

LRID  of  next  (or  first)  record 
in  file 

PREID 

192 

LP.ID  of  preceeding  (or  last)  record 

LRLEN 

193 

Logical  record  length  in  characters 

FSTAT 

194 

File  status  (from  DKFIL) 

NDA 

195 

Maximum  number  of  direct  access  data 
set 

IDHTR 

196 

Data  handler  trace  switch 

IDHER 

197 

User  error  handling  switch 

IDKER 

198 

Data  handler  error  number 

SEYSN 

199 

Subsystem  name  (up  to  8  characters) 

SSYSN 

200 

Subsystem  name  (up  to  8  characters) 

*  initialized  to  value  of  IBT5T 

**  initialized  to  1 

initialized  to  value  of  NEBT 
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(2)  If  this  LRS  is  not  the  first  LRS,  LRS  ID  of  the  LRS  written 
previously  for  this  LR. 

Chain  Option 

(1)  If  this  LRS  is  the  first  one  in  the  file,  zero. 

(2)  If  this  is  the  first  LRS  of  a  LR.  LR  ID  for  the  first  LRS 
of  the  previously  written. 

KLRHF  contains  the  following: 

No  Chain  Option 

(1)  If  LRS  not  the  last  LRS  in  LR,  LRS  ID  of  the  subsequent 

LRS. 

(2)  If  LRS  is  the  last  LRS  in  LR,  or  the  point  option  is  not  in 
effect,  zero. 


Chain  Option 

(1)  If  LRS  is  the  last  LRS  in  CR.  LR  ID  for  the  first  LRS  of 
the  subsequent  record. 

The  actual  data  is  stored  next  followed  by  the  unused  characters 
in  the  last  SU. 

'Program  Common  Structure 

The  great  majority  of  internal  variables  and  arrays  used  by  the 
DH  are  located  in  blank  C(3MM0N  (Figure  8).  Common  consists  of  a 
fixed  ares  and  a  pool  (dynamic)  area.  The  first  sections  in  the 
fixed  area  contain  system-wide  and  DH  communications  variables  and 
arrays.  The  second  section  contains  the  DH  internal  variables  and 
arrays.  All  three  sections  are  documented  in  Table  1.  All  positions 
and  lengths  in  Table  1  are  given  in  terms  of  SU's.  All  elements  in 
this  section  that  need  to  be  initialized  are  done  so  during  DH  ini¬ 
tialization. 

The  pool  area  contains  the  four  DH  tables;  the  data  set  table 
(DST),  the  open  file  table  (0FT),  the  buffer  table  (BT),  and  the  BT 
priority  queue.  There  is  an  unused  area  at  the  end  of  common. 

The  DST  contains  an  entry  for  each  data  set  that  is  currently  in 
use  by  the  DH  (Figure  9).  The  high-order  half  of  KDSLU  contains  four 
status  bits  known  as  the  open,  old,  save,  and  share  bits,  whose  posi¬ 
tions  are 'given  by  the  C0MM0N  variables  N60PN,  NB0LO,  NBSA,  and 
NBSHR,  respectively  (Table  1).  The  open  bit  indicates  whether  or  not 
the  data  set  is  open  to  the  host  operating  system.  The  old  bit  indi¬ 
cates  whether  or  not  the  data  set  existed  before  the  current 
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^stem- 
wlde  vari¬ 
ables  and 
arrays  (75 
SU*s) 

3ata 
handier 
internal 
variables 
and  arrays 
(III)  SUs) 

data 
handler 
communica¬ 
tions  variables 
and  orroys 
(l4SU's) 

data 

set 

toble 

(voriable 

length) 

open 

file 

toble 

(currently 

H25SUs) 

buffer 

table 

(variable 

length) 

buffer 

table 

priority 

queue 

(varioble 

length) 


unused 

(varioble 

length) 


fixed  area  (200  SU's) 


pool  (  )  area 
(currently  9800  SU’s) 


Figure  8.  Common  Layout 
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Open  stolus  bit 
Old  status  bit 
Save  status  bit 


Figure  9.  Data  Set  Table  Loyout 


execution  of  the  DH.  The  save  bit  indicates  whether  or  not  the  data 

set  is  to  be  saved  at  the  end  of  the  current  execution.  The  share 

bit  indicates  whether  the  data  set  can  be  shared  with  another, 
concurrently-executing  DH  task.  The  low-order  half  of  KDSLU  is  the 
logical  unit  number. 

KOSFN  is  the  data  set  name,  KDSPR  is  the  PR  size  (in  SU's), 

KDSPB  is  the  number  of  whole  PR's  per  block,  KOSPL  is  the  number  of 
SU's  in  the  last  (partial)  PR  of  a  block  if  the  block  does  not  end  on 
a  PR  boundary  (it  is  zero  otherwise),  KDSSU  is  the  block  size  (in 
SU's),  KOSFD  is  the  entry  number  of  the  next  free  FD  entry,  KDSFS  is 

the  number  of  blocks  initialized  in  the  data  set,  and  KDSWN  is  the 

postion  of  KDSWN  within  the  FST. 

The  0FT  contains  an  entry  for  each  file  that  is  currently  in  use 
for  output  by  the  DH  (Figure  10).  K0FFN(4)  is  the  file  name.  K0FFL 
and  K0FLL  are  the  LR  ID'S  of  the  first  and  last  LR's,  respectively, 
that  were  written  for  the  file.  K0FNB  is  the  block  number  of  the 
next  block  to  be  added  to  the  file.  K0FLB  is  the  block  number  of  the 
last  block  that  was  written  for  the  file.  The  high-order  half  of 
K0FFD  is  the  entry  number  of  the  FD  entry  associated  with  this  file. 
The  bits  in  the  low-order  half  of  K0FFD  constitute  the  data  set 
number  (DST  entry  number)  of  the  data  set  to  which  the  file  belongs. 
The  extreme  low-order  portion  of  the  low-order  half  of  K0FFD  contains 
three  status  bits  known  as  the  chain,  pack,  and  protect  bits,  whose 
positions  are  given  by  the  C0MM0N  variables  NBCHN,  NBPAK,  and  NBPR0. 
The  chain  and  pack  bits  indicate  whether  or  not  the  chain  and  pack 
options  are  in  effect  for  the  file.  The  protect  bit  indicates 
whether  or  not  write  protection  is  in  effect  for  the  file.* 

The  BT  contains  an  entry  for  each  block  of  a  data  set  that  is 
currently  in  main  storage  (Figure  11).  KBTNS  is  the  data  set  number 
(DST  entry  number)  of  the  data  set  to  which  this  block  belongs. 

KBTBL  is  the  block  number  of  the  block.  KBTQ  is  the  segment  number 
of  the  segment  which  was  requested  when  the  block  was  read  into  main 
storage,  and  KBTPP  is  the  position  in  C0MM0N  of  the  SU  immediately 
proceeding  the  beginning  of  the  segment.  KBTL  and  KBTTR  are  the  seg¬ 
ment  and  block  numbers,  respectively,  of  the  LR  that  was  most 
recently  referenced  in  this  BT  entry.  KBTCN  is  the  position  within 
this  LR  of  the  first  (data)  character  (of  a  set)  that  was  requested. 
KSTDP  is  the  position  in  C0MM0N  of  the  SU  that  contains  this  charac¬ 
ter.  KBTNC  is  the  number  of  characters  in  the. first  segment  of  this 
LR.  KBTSW  contains  three  status  bits  known  as  the  written- into, 
write- in- progress,  and  read-in-progress  bits,  whose  positions  are 
given  by  the  C0MM0N  variables  NBWIN,  NBWIN,  NBRIT,  and  NBRED,  respec¬ 
tively.  The  written-into  bit  indicates  whether  or  not  the  block  has 
been  modified  in  this  BT  entry.  The  write-in  progress  bit  indicates 
whether  or  not  an  output  operation  is  in  progress  for  the  block.  The 
read-in-progreas  bit  indicates  whether  or  not  an  input  operation  is 
in  progress  for  the  block.  KBTFN(4)  is  the  name  of  the  file  to  which 
the  block  belongs.  KBTFI  and  KBTPI  have  the  same  values  as  KLRHF  and 
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Figure  10.  Open  File  Table/File  Directory  Entry  Loyout 


KBTNS 


data  set  No.-OST 


KBTBL 


Buffer  No.  I  Buffer  No.  2  KBTQ 


block  No. 


segment  No.  requested 


KBTPP 


KBTL 


KBTTR 


su  position  proceeding  segment 
most  recently  referenced  segment  No. 


t|  II 


block  No. 


KBTCN  first  doto  chorocter  position 

KBTOP  su  containing  .first  doto  ctr. 

No.  of  ctrs.  in  first  segment 
KBTNC  /  heoder 

C  written  into  bit 

KBTSW _  write  in  progress  bit 

- —  read  in  progress  bit 

KBTFN(4)  file  nome 


KBTFI 


KLRHF  for  KBTL 


KBTPI 


KLRHP  for  KBTTR 


KBTLN 


No.  ctrs.  in  LR 


data 


buffer  (currently  256  SUVm 


Figure  II.  Buffer  Table  Loyout 


Figure  12.  BT  Priority  Que  Layout 


KLRHP,  respectively,  in  the  LR  header  of  the  LR  given  by  KBTL  and 
KBTTR.  KBTLN  is  the  number  of  characters  in  the  LR. 

The  BT  priority  queue  contains  an  SU  entry  for  each  BT  entry 
(Figure  12).  The  high-order  half  of  the  i'th  BT  priority  queue  entry 
is  the  entry  number  of  the  BT  entry  that  was  referenced  immediately 
after  the  i'th  BT  entry.  The  low-order  half  of  the  i'th  BT  priority 
queue  entry  is  the  entry  number  of  the  BT  entry  that  was  referenced 
immediately  before  the  i'th  BT  entry.  Hence,  the  BT  priority  queue 
imposes  a  most-recently-referenced-to-least-recently-referenced  ord¬ 
ering  on  the  BT  entries.  A  more  recently  referenced  BT  entry  is  said 
to  have  a  higher  priority  than  a  less  recently  referenced  BT  entry. 

A  block  in  a  higher-priority  BT  entry  will  be  retained  in  main 
storage  longer  than  a  block  in  a  lower- priority  one. 

The  DH  includes  a  routine  which  produces  a  dump  of  blank  C0MM0N. 
All  items  are  identified  in  the  same  manner  as  they  are  in  this  docu- 
mentaion.  The  values  are  given  in  decimal  digits  and  characters  as 
applicable  except  for  KDSLU,  K0FFD,  KBTSW,  the  buffer  contents  of  the 
BT  entries,  and  the  BT  priority  queue  entries,  which  are  given  in 
hexadecimal  digits.  An  annotated  dump  is  given  in  Appendix. A. 

Definitions 

Data  Set  Block  -  Fixed-sized  unit  of  information  stored  on  a  data 

set.  The  actual  information  read  (or.  written)  from  the  disk  and 
to  the  local  program  1/0  buffer  area. 

Program  1/0  Buffer  -  Fixed-sized  unit  of  storage  in  the  local  program 
space  to  be  used  to  store  data  read  from  (to  be  written  to)  disk 
storage. 

Physical  Record  -  Fixed-sized  unit  of  information  measurement  which 
must  be  equal  to  or  less  than  the  size  of  the  data  set  block. 


2  APPLYING  THE  DATA  HANDLER 


The  use  of  the  data  handler  (DH)  within  a  computer  system  appli¬ 
cation  program  requires  the  review  and  application  of  two  data 
handler  routines.  The  first  routine,  DKNIT,  initializes  the  data 
handler,  allows  the  system  programmer  to  define  the  system  parameters 
to  the  data  handler,  and  builds  the  necessary  tables  for  DH  execu¬ 
tion. 


The  system  programmer  must  review  the  definition  of  each  parame¬ 
ter  and  variable  in  this  routine  and  define  the  values  with  respect 
to  the  actual  operating  system  characteristics. 

This  routine  must  be  the  first  routine  called  by  the  application 
system. 

When  all  processing  has  been  completed  the  application  system 
should  call  DKXIT  to  logically  close  all  DH  managed  data  sets. 

During  the  period  after  the  call  to  DKNIT  and  before  DKXIT  all 
application  programs  can  utilize  the  DH  application  routines  to  read 
and/or  work  information  from/to  the  DH  datasets. 
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3  APPLICATION  COMMAND  SUBROUTINE  DESCRIPTION 
Definitions 

Several  parameters  are  kept  in  COMMON,  rather  than  being  passed 
as  arguments.  These  include: 

FILENAME  -  the  name  of  the  file  being  operated  on;  it  contains 
up  to  16  characters. 

NDS  -  the  data  set  number,  usually  1,2,3,  or  4. 

PREID  -  the  logical  record  identifier  of  the  preceding  record  in 
the  file. 

FOLID  -  the  logical  record  identifier  of  the  following  record  in 
the  file. 

LRLEN  -  the  logical  record  length,  in  characters. 

FSTAT  -  the  file  status  (see  DKFIL  4.8). 


Learning  the  Commands 

The  logical  order  for  learning  the  commands  and  functions  is  to 
read  the  descriptions  in  the  following  order; 

1.  Access  to  Data. 

1.  LOK/UNLOK  -  to  obtain  controlled  access  to  information. 

2.  Data  Sets. 

1.  DKNNDS  -  To  find  a  data  set  number. 

2.  DKDSN  -  To  find  data  set  name 

3.  DKSET  -  To  obtain  general  information. 

3.  Files. 

1.  DKOPN  -  To  create  and/or  open  a  file  for  writing. 

2.  DKPUT  -  To  write  information. 

3.  DKINS  -  To  write  (insert)  information 

4.  DKGET  -  To  read  information 

5.  OKOEL  -  To  delete  information. 

6.  DKRNM  -  To  rename  the  file 

7.  DKFIL  -  To  obtain  general  information 

8.  DKLEN’"-  To  obtain  the  length  of  a  record. 

9.  DKLOS  -  To  disallow  writing 


RECORD  DELETION 
DKDEL 


PURPOSE 


To  delete  a  specific  record  within  a  file  or  to  delete  a  complete  file. 

GENERAL  FORM 

CALL  DKDEL  (RECID) 

where  RECID  is  a  zero  or  the 

record  id  for  an 
existing  record. 

(INPUT) 

FIELD  OPTIONS 


FIELD 


OPTIONS _ DEFAULT 


1.  RECID  a.  valid  record  id  No  Default 

b.  zero  (0)  to  delete 
all  records  in 
the  file  FILENAME 


SPECIAL  NOTES 


The  programmer  must  set  variables  NDS  and  FILENAME  in  common  before  the 
subroutine  is  called. 
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EXECUTION  PROCEDURE 


The  system  will  delete  the  record  specified  from  the  data  set  NDS.  If 
the  RECID  is  zero,  the  entire  file  defined  in  FILENAME  will  be  deleted 
from  data  set  NDS. 
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FIND  DATA  SET  NAME 
DKDSN 


PURPOSE 


To  find  the  dataset  name  when  the  dataset  number  1s  known. 

GENERAL  FORM 


CALL  DKDSN (DSNM) 

where  is  returned  as  the  dataset 

name-  (output) 


FIELD  OPTIONS  -  None 
SPECIFIC  NOTES 


The  programmer  must  set  variables  NDS  and  FILENAME  in  common  before  the 
subroutine  is  called. 


EXECUTION  PROCEDURES 


The  system  will  locate  the  data  set  specified  by  NDS  and  return  the 
dataset  name.  If  the  data  set  is  not  found,  the  routine  will  return  the 
next  data  set  w-ith  a  larger  NDS  valve.  NDS  will  be  changed  to  point  to 
the  new  data  set.  If  no  more  data  sets  are  available,  NDS  and  DSNM  will 
be  zeroed. 
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OBTAIN  FILE  INFORMATION 

mil 


PURPOSE 


To  obtain  the  general  information  about  a  specified  file. 


GENERAL  FORM 


CALL  DKFIL 


FIELD  OPTIONS  -  None 
SPECIAL  NOTES 


The  programmer  must  define  NOS  and  FILENAME  in  conmon  before  this  sub¬ 
routine  is  called. 


EXECUTION  PROCEDURES 


FSTAT  is  returned  in  common  as 

1  -  if  the  file  does  not  exist 

2  -  if  the  file  is  closed 

3  -  if  the  file  is  open 

PREID  is  returned  in  cofimon  as  the  record  id  of  the  first  record  in  the 
file. 

FOCIO  is  returned  in  common  as  the  record  id  of  the  last  record  in  the 
file. 
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GET  INFORMATION  FROM  DISK 
DKGET 


PURPOSE 


To  obtain  information  from  a  file  on  disk  storage. 


GENERAL  FORM 


CALL  DKGET  (RECID.  AREA,  LI,  L2,  NC) 


where 


RECID 

is  the  logical  record 
identifier.  (INPUT) 

AREA 

is  the  location 
into  which  the 
information  is  to 
be  placed.  (OUTPUT) 

LI 

is  the  first  charac¬ 
ter  to  be  read 
from  the  record.  (INPUT) 

L2 

is  the  last  charac¬ 
ter  to  be  read 
from  the  record.  (INPUT) 

NC 

is  the  actual 
number  of  charac¬ 
ters  read  from 
the  record.  (OUTPUT) 

FIELD  OPTIONS 


FIELD 

OPTIONS 

DEFAULT 

1.  RECID 

a.  valid  record 

No  Default 

id 
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FIELD  OPTIONS 


OPTIONS  DEFAULT 


a.  one  computer  No  Default 

word,  variable  name. 

b.  the  first  computer 
word  to  be  used 

to  hold  the  data. 

An  element  of  a 
dimensioned  array. 


a.  less  than  one  No  Default 

or  greater  than  the 

length  of  the  logical 
record,  it  is  inter¬ 
preted  as  being  equal 
to  one. 

b.  the  first  character 
to  be  read. 


a.  greater  than  the  No  Default 
nwnber  of  characters 

in  the  specified 
logical  record  or  if 
less  than  LI,  it  is 
interpreted  as  being 
equal  to  the  last 
character  in  the  re¬ 
cord. 

b.  the  last  character 
to  be  read. 

c.  zero  -  is  inter¬ 
preted  as  being  equal 
to  the  last  charac¬ 
ter  in  the  record. 


Actual  number  of  No  Default 

of  characters  read. 


SPECIAL  NOTES 


The  programmer  must  set  NDS  in  common  before  a  call  to  this  subroutine. 
The  programmer  can  read  an  entire  logical  record  of  unknown  length  by 
setting  LI  and  L2  equal  to  zero.  The  programmer  must  define  RECID, 
AREA,  LI  and  L2. 


EXECUTION  PROCEDURES 


The  system  will  read  the  requested  information  (LI,  L2)  from  the 
requested  record  RECID  located  on  data  set  NDS.  The  data  will  be  stored 
starting  with  word  AREA.  The  system  will  return  NC  as  the  number  of 
characters  actually  placed  into  AREA. 


RECORD  INSERTION 
OKINS 


PURPOSE 


To  insert  a  record  at  the  beginning  of  a  point  file  or  to  insert  a 
record  after  a  specified  record  in  a  point  file. 


GENERAL  FORM 


CALL  OKINS  (RECID,  AREA,  LI,  L2) 


where  RECID 


AREA 

LI 

L2 


is  the  logical  record 
identifier  after  which 
the  new  record  is  to 
be  entered.  (INPUT) 

Is  the  record  id  of 
the  new  record;  (OUTPUT) 
is  the  first  word  of 
the  information  to  be 
placed  into  the  new 
record.  (INPUT) 
is  the  first  character 
in  the  record  to  receive 
the  first  character  in 
AREA.  (INPUT) 
is  the  last  character 
in  the  record  to  receive 
information  from  AREA. 
(INPUT) 


FIELD  OPTIONS 


FIELD 


OPTIONS  DEFAULT 


1.  RECID 


a.  record  id  after  No  Default 
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FIELD  OPTIONS 


FIELD 


OPTIONS  DEFAULT 


which  the  new  re¬ 
cord  will  be  placed. 

b.  zero  to  indicate 
placement  as  the 
first  record  in 
the  file. 

c.  computer  output, 
record  id  of  new 
data  record. 


2.  AREA  ,  the  location  in  No  Default 

core  from  which  the 
writing  will  start. 


3.  LI  a.  is  the  first  No  Default 

character  in  the 
record  to  receive  . 
the  first  charac- . 
ter  in  AREA, 
b.  zero  to  indicate 
start  with  the 
first  chracter. 


4.  L2  is  the  last  charac-  No  Default 

ter  in  the  record 
to  receive  informa¬ 
tion  from  AREA. 


SPECIAL  NOTES 


The  programmer  must  set  NOS  in  common.  If  the  programmer  is  writing  a 
new  record,  FILENAME  must  be  set  in  common.  The  programmer  must  define 
RECID,  AREA,  LI  and  L2  before  calling  this  subroutine. 
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EXECUTION  PROCEDURES  ' 


A  new  record  will  be  created  after  record  RECID.  If  RECID  is  zero,  a 
new  record  will  be  added  to  the  beginning  of  the  file.  The  system  will 
place  the  first  character  in  AREA  in  the  LI  character  location  in  the 
new  record.  Characters  will  be  copied  from  AREA  until  the  L2  character 
has  been  written  into  the  new  file.  The  record  id  for  the  new  record 
will  be  returned  in  RECID. 


OBTAIN  LOGICAL  RECORD  LENGTH 
DKLEN 

PURPOSE 

To  obtain  the  logical  record  length  of  an  existing  record. 

GENERAL  FORM 

CALL  DKLEN  (RECID) 

where  RECID  is  an  existing  • 

logical  record 
id.  (INPUT) 

FIELD  OPTIONS  -  None 

SPECIAL  NOTES 

The  programmer  must  set  NDS  in  COMMON  before  calling  this  routine. 

EXECUTION  PROCEDURES 

The  system  will  obtain  the  length  of  record  RECID  in  data  set  NDS  and 
return  it  in  variable  LRLEN  in  common.  The  system  sits  PREID  and  FOLID 
also. 
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CLOSE  A  FILE 
OKLOS 


PURPOSE 


To  make  a  file  unavailable  for  writing. 


GENERAL  FORM 


CALL  OKLOS 


FIELD  OPTIONS  -  None 
SPECIAL  NOTES 


The  progranmer  must  set  NOS  and  FILENAME  in  common  before  calling  this 
routine. 


EXECUTION  PROCEDURES 


All  records  in  core  for  FILENAME  are  marked  for  writing  and  will  be 
placed  onto  the  disk  NOS.  The  file  will  be  marked  as  closed  and  no  one 
will  be  allowed  to  write  into  the  file  until  another  DHOPN  is  issued. 
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FIND  DATASET  NUMBER 
DKNDS 


PURPOSE 


To  find  the  data  set  number  when  the  data  set  name  is  known. 


GENERAL  FORM 


CALL  (DSNAM,  OSNO) 


is  the  name  of  • 
the  data  set.  (INPUT) 
is  the  number  of 
the  data  set.  (OUTPUT) 


where  DSNAM 

DSNO 


FIELD  OPTIONS  -  None 


SPECIAL  NOTES  -  None 


EXECUTION  PROCEDURES 


The  system  searches  the  data  set  name  list  and  returns  the  data  set 
number  DSNO.  If  the  dataset  is  not  found,  DSNO  will  be  returned  as 
zero. 
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DATA  HANDLER  INITIALIZATION 
DKNIT 


PURPOSE 


To  initialize  the  data  area  in  core  for  the  data-handler  and  to  estab 
lish  the  dataset  name  -  logical  reference  number  association. 


GENERAL  FORM 


CALL  DKNIT 


FIELD  OPTIONS  -  None 


SPECIAL  NOTES 


This  routine  should  be  called  once  at  the  beginning  of  the  application 
system. 


EXECUTION  PROCEDURES 


The  system  will  establish  all  in  core  data  elements  prior  to  the  first 
use  of  any  other  data-handler  subro’Jtine. 


OPEN  A  FILE 
DKOPN 


PURPOSE 


To  open  a  new  or  existing  file. 


GENERAL  FORM 


CALL  DKOPN  (lOP) 


where  lOP  is  the  storage  option 

code  for  a  new  file 
only.  (INPUT) 


FIELD  OPTIONS 


1.  lOP  a.  new  files  only  No  Default 

0  -  neither  point 
nor  pack 

1  -  point  only 

2  -  pack  only 

3  -  point  and  pack 
b.  not  used  for 

existing  files 


SPECIAL  NOTES 


The  programmer  must  set  NDS  and  FILENAME  in  COMMON.  lOP  is  only  applied 
if  the  file  is  new. 
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OPEN  A  FILE 
DKOPN 


EXECUTION  PROCEDURES 


The  file  FILENAME  is  opened  for  writing  in  data  set  NOS  using  the  origi¬ 
nal  storage  option  given  by  the  original  DKOPN.  If  the  file  does  not 
exist,  the  file  is  created. 
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WRITE  INFORMATION  TO  A  RECORD 
DKPUT 


PURPOSE 


To  write  information  to  a  record. 


GENERAL  FORM 


CALL  DKPUT  (RECID,  AREA,  LI,  L2) 


where  RECIO  is  a  record  id  in  a 

data  set.  (INPUT)  (OUTPUT) 

AREA  is  the  information  to 

be  written.  (INPUT) 

LI  is  the  first  character  in 

the  record  to  receive  the 
first  character  in  AREA. 
(INPUT) 

L2  is  the  last  character  in 

the  record  to  receive  data 
from  AREA.  (INPUT) 


FIELD  OPTIONS 


1.  RECID  .a.  zero  -  to  write  No  Default 


a  new  record  at  the 
end  of  a  file. 

(INPUT) 

b.  a  valid  record  id 

of  an  existing  record. 
(INPUT) 

c.  record  id  of  the 
record  written  into. 
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FIELD  OPTIONS 


FIELD  OPTIONS  DEFAULT 


(OUTPUT) 


2.  AREA  a.  one  computer  No  Default 

word,  variable  name 
b.  the  first  computer 
word  to  be  used 
to  hold  the  data. 

An  element  of  a 
dimensioned  array. 


3,  LI  .  first  character  in  No  Default 

the  record  to  receive 
information. 


4.  L2  a. 

b. 


positive  -  last  No  Default 
character  in  the 
record  to  receive  infor¬ 
mation  from  AREA, 
negative  -  truncation 
of  the  logical  record 
will  occur.  The  last 
character  will  be  the 
absolute  valve  of  L2. 


SPECIAL  NOTES 


The  programmer  must  set  NDS  and  FILENAME  in  COMMON. 


EXECUTION  PROCEDURE 


If  RECID  is  initially  zero,  a  new  record  at  the  end  of  the  file  will  be 
generated.  The  first  character  in  AREA  will  be  placed  in  the  LI  charac¬ 
ter  position  in  the  record.  Copying  will  continue  until  a  character  has 


I' 


been  written  into  the  absolute  value  of  L2.  If  L2  is  negative  the 
existing  record  will  be  reduced  to  L2  characters. 
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Tsr 


RENAME  A  FILE 
DKRNM 


Lv 


PURPOSE 


To  change  the  name  of  an  existing  file. 

GENERAL  FORM 


CALL  DKRNM  (OCDNM,  NEWNM) 


where  OLDNM 

NEWNM 


is  the  current  file 
name.  (INPUT) 
is  the  new  file 
name.  (INPUT) 


FIELD  OPTIONS  -  None 


SPECIAL  NOTES 


The  programmer  must  set  NDS  in  COMMON  before  applying  this  routine. 

EXECUTION  PROCEDURE 

The  old  name  will  be  changed  to  the  new  name. 
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OBTAIN  DATASET  INFORMATION 
DKSET 


PURPOSE 


To  obtain  the  current  information  related  to  a  specific  document. 


GENERAL  FORM 


CALL  DKSET  (LBLK,  NBU,  NTALL) 


is  the  block  len.gth 
in  standard  units.  (OUTPUT) 
is  the  number  of  blocks 
used.  (OUTPUT) 
is  the  total  number  of  blocks 
used.  (OUTPUT) 


FIELD  OPTIONS  -  None 


SPECIAL  NOTES 


where  LBLK 

NBU 
NTALL 


The  programmer  must  set  NOS  before  calling  this  routine. 


EXECUTION  PROCEDURE 


The  system  will  set  all  three  parameters  and  return. 
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END  DATA  HANDLER 
DKXIT 

PURPOSE 

To  clear  all  batters  and  write  out  all  changes  to  the  disks. 

GENERAL  FORM 

CALL  DKXIT 

FIELD  OPTIONS  -  None 
SPECIAL  NOTES 

This  routine  should  be  called  once  before  exiting  from  the  application 
system. 

EXECUTION  PROCEDURES 

The  system  will  logically  end  all  processing  of  data.  All  batters  will 
be  cleared  and  data  change  written  to  disk. 


ACCESS  TO  FILES 

LOCK 

UNLOK 


PURPOSE 


To  obtain  access  to  existing  files. 


GENERAL  FORM 


CALL  LOCK  (I NO) 
CALL  UNLOK 


where  I NO  indicates  control 

requested 


FIELD  OPTIONS 


FIELD 


OPTION  DEFAULT 


1.  IND  a.  0  -  unconditional  No  Default 

b  -  1  -  conditional 


SPECIAL  NOTES 


During  the  actual  execution  of  the  data-handler  in  an  interactive  or 
multiprogramming  environment,  several  users  may  be  executing  different 
copies  of  the  code  at  the  same  time.  Some  of  the  users  may  wish  to 
access  (to  read  and/or  write)  the  same  files  at  the  same  time.  The 
"multi-user"  feature  will  permit  concurrently  executing  programs  to 
share  the  use  of  files.  Shared  use  of  these  resources  must  be  strictly 
controlled  in  order  to  ensure  that  one  program  does  not  interfere  with 
the  correct  execution  of  others.  This  control  takes  the  form  of  syn¬ 
chronizing  use  of  these  resources  on  the  part  of  the  programs  invovled. 
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ACCESS  TO  FILES 

LOCK 

UNLOK 


When  a  program  requires  use  of  a  resource,  it  must  request  control  of 
that  resource  from  the  operating  system.  Control  of  a  resource  can  be 
either  exclusive  or  shared.  Exclusive  control  of  a  resource  guarantees 
that  no  other  program  will  be  granted  access  to  that  resource  (write 
access).  Shared  control  guarantees  that  no  other  program  will  be 
granted  exclusive  control  of  that  resource,  but  other  programs  will  be 
granted  shared  control  of  that  resource  (read  only  access). 

A. request  for  either  kind  of  control  of  a  resource  can  be  either  condi¬ 
tional  or  unconditional.  For  conditional  request,  control  is  granted 
only  if  the  resource  is  immediately  available.  The  requesting  program 
is  informed  as  to  whether  or  not  control  was  granted.  For  unconditional 
requests,  control  is  granted  as  soon  as  the  resource  becomes  available. 
The  requesting  program  may  have  to  wait  for  an  indefinite  amount  of 
time.  This  eventuality  is  entirely  transparent  to  the  program  itself. 

When  a  program  has  finished  using  a  resource,  it  must  relinquish  control 
of  that  resource  so  that  it  becomes  available  for  use  by  other  programs. 

REQUESTING  AND  RELINQUISHING  CONTROL  OF  RESOURCES  IS  THE  PROGRAMMER'S 
RESPONSIBILITY.  Two  subroutines,  LOCK  and  UNLOK,  have  been  made  avail¬ 
able  for  this  purpose. 


Required  Programming  Before  Calling  LOCK  or  UNLOK 
INTEGER  RSRCS 

COMMON  /LOCKC/  RSRCS  (7,40),  NRSRCS 

Before  calling  LOCK  or  UNLOK,  you  must  describe  the  resources  to  be 
requested  or  relinquished  via  the  array  RSRCS.  Each  column  corresponds 
to  one  resource.  The  number  of  resources  described  in  RSRCS  must  be 
defined  in  the  .variable  NRSRCS. 

Before  a  call  to  LOCK,  RSRCS(2,I),  RSRCS(3,I),  RSRCS(4,I),  and 
RSRCS (5, 1)  must  contain  the  name  of  the  I'th  resource  requested. 

RSRCS (1,1)  must  contain  the  number  of  the  data  set  on  which  this 
resource  resides.  RSRCS(7,I)  should  ■  1  if  exclusive  control  of  this 
resource  is  requested,  0  if  shared  control  is  requested.  NRSRCS  should 
contain  the  number  of  resources,  RSRCS(6,I)  should  not  be  used  within  a 
processing  program. 

LOCK,  as  its  name  implies,  is  to  be  used  to  request  control  of 
resources. 
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ACCESS  TO  FILES 

LOCK 

UNLOK 


LOCK  has  a  single  argument,  the  integer  variable  IND,  which  should 
»  1  if  the  request  is  conditional,  0  if  the  request  is  unconditional. 

If  IND  ■  1,  LOCK  will  return  the  status  of  the  request  via  the  argument 
IND.  IND  «  1  if  control  of  all  requested  resources  was  granted,  0  if 
control  over  none  of  the  resources  was  granted  due  to  the  non¬ 
availability  of  one  or  more  of  the  resources.  If  the  request  was  uncon¬ 
ditional,  then  control  of  all  requested  resources  was  granted  (IND  was 
not  modified  and  still  =  0).  Note  that  LOCK  (or  UNLOK)  never  modifies 
LOCKC. 

UNLOK  is  to  be  used  to  relinquish  control  of  resources.  UNLOK  has 
no  arguments,  since  control  of  resources  is  always  relinquished  uncon¬ 
ditional  ly. 


Application  Rules 

I 

The  following  rules  must  be  strictly  observed: 

(1)  Control  of  a  resource  should  not  be  requested  until  it  is 
needed; 

(2)  A  resource  must  not  be  used  until  after  its  control  has  been 
requested  and  granted; 

(3)  a.  The  use  of  OKOPN,  OKPUT,  DKINS,  DKLOS,  DKSET,  DKRNM, 

OKXIT,  or  OKCLR  in  connection  with  a  resource  requires 
EXCLUSIVE  CONTROL  of  that  resource; 

b.  The  use  of  DKFIL,  DKLEN,  or  DKGET  in  connection  with  a 
resource  requires  shared  or  exclusive  control  of  that 
resource; 

c.  The  use  of  DKNDS,  OKNIT,  or  DKDMP  is  unrestricted; 

(4)  Control  of  a  resource  must  not  be  relinquished  until  it  is 
consistent  with  respect  to  both  itself  and  other  resources; 

(5)  Control  of  a  resource  should  be  relinquished  as  soon  as  it  is 
no  longer  needed. 

(6)  A  resource  must  not  be  used  after  its  control  has  been  relin¬ 
quished; 

(7)  The  logic  of  execution  should  be  such  that:  UNLOK  is  not 


ACCESS  TO  FILES 

LOCK 

UNLOK 


called  without  a  previous  call  to  LOCK;  two  calls  to 
LOCk/Onlqk  are  never  made  wUhout  an  intervening  cTTl  to 
UnlOK/LOCK;  LOCK  is  not  called  without  a  subsequent  call  to 
JMW. - -  - - 

(8)  a.  The  same  resource  must  not  be  referenced  by  two  different 

columns  in  RSRCS; 

b.  The  maximum  number  of  resources  to  be  locked  is  40; 

(9)  No  assumptions  may  be  made  regarding  the  contents  of  a 
resource  at  the  time  its  control  is  granted. 

Failure  to  observe  one  or  more  of  the  above  rules  will  not  neces¬ 
sarily  result  in  the  occurrence  of  a  perceptible  error  condition  (such 
as  an  ABENO),  but  resource  integrity  may  nevertheless  be  seriously 
impaired^.  It  is  most  important  that  great  care  in  coding  be  exercised. 
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4  SUBROUTINE  FUNCTIONS 


Appendix  B  briefly  describes  the  functions  performed  by  each 
subprogram.  This  list  is  ordered  by  subroutine  name. 

Subroutines  are  divided  into  two  general  types:  (1)  application 
subroutines,  and  (2)  function  subroutines.  The  user's  apply  applica¬ 
tion  programs  application  subroutines  to  request  the  data  handler  to 
perform  work.  The  application  and  function  subroutines  use  the  func¬ 
tion  subroutines  to  actually  perform  work  within  the  data  handler. 


5  ERROR  MESSAGES 


The  following  data-handler  errors  are  defined  below: 


OATA-HANOLER  PACKAGE  ERROR  NUMBERS  PAGE  1 


ERROR  ROUTINE  CONDITION 

NO. 


1  DKNIT  -  SYST  COMMON  NOT  INITIALIZED 

2  DKNIT  -  NOT  ENOUGH  SPACE  FOR  1  BUFFER 

3  OKGO  -  NBSGN  +  NABLK  .NE.  UBU 

4  DKODS  -  OLD  FILE  NOT  A  DH  FILE 

5  DKODS  -  CAN’T  PROCESS  OLD  FILE  -  BLOCK  SIZE  TOO  BIG 

6  DKODS  -  ERROR  READING  OLD  FILE  HEADER 

.  7  DKODS  -  ERROR  OPENING  OLD  FILE 

8  OKOOS  -  ERROR  OPENING  NEW  FILE 

9  OKARG  -  NDS  INVALID 

10  OKCOS  -  ERROR  CLOSING  FILE  &  SAVING 

11  OKCOS  -  ERROR  CLOSING  FILE  &  DELETING 

12  DKRBL  -  READ  INTO  AN  ACTIVE  BUFFER  -  INTERNAL  ERROR  IN  DH  OR 

POLLUTED  BUFFERS 

13  OKASG  -  CHARS  IN  FILE  NAME  MORE  THAN  ALLOWED 

14  OKWAT  -  INTERNAL  ERROR  -  POLLUTED  BT  EMPTY  -  WAIT  BIT  IS  ON 

15  DKRBL  •  I/O  ERROR  DURING  READ 

16  OKWBL  -  WRITE  FROM  ACTIVE  BUFFER 

17  OKWBL  -  I/O  ERROR  DURING  WRITE 

18  OKOOS  -  CAN'T  PROCESS  OLD  FILE  -  NBSGNNBBLK  INCONSISTENT 
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DATA-HANDLER  PACKAGE  ERROR  NUMBERS  (CONT’D) 


ERROR  ROUTINE  CONDITION 

NO. 


WITH  THOSE  ASSIGNED  VIA  DKNIT 


19 

DKRNM 

• 

OLD  FILENAME  DOES  NOT  EXIST 

20 

DKGET 

• 

GET  WORK  THAN  MAYGP  CHARS 

21 

DKNSG 

• 

CONTINUED  BIT  NOT  SET  EXPECT  TO  READ  MORE  SEGMENTS- 
LOGICAL  INCONSISTENCY  IN  FILE 

22 

OKNSG 

• 

CONTINUED  BIT  SET  BUT  NEXT  LRID  »  OLOGICAL 

INCONSISTENCY  IN  FILE 

23 

DKSTO 

m 

LR  SEGMENT  NOT  IN  PP  (NON-ZERO  SEG  COUNT  IN  HEADER) 

24 

DKSTO 

- 

PP  HAS  ZERO  SEGS;  ILLEGAL  RECID 

25 

DKFND/DKGL2  -  ACCESS  OF  A  DELETED  LR  SEGMENT 

26 

DKGET 

- 

ILLEGAL  RECID  (»0) 

27 

DKRNM 

- 

INVALID  OLD  FILENAME 

28 

OKRNM 

INVALID  NEW  FILENAME 

29 

DKPUT 

- 

Ll.GT.LRLEN+1  ON  UPDATE  (EXTEND) 

30 

DKPUT 

> 

FILE  NOT  OPEN 

31 

DKPUT 

- 

L2.NE.0  ON  ADO 

32 

DKPUT 

> 

TRY  TO  PUT  MORE  THAN  MAXGP  CHARS 

33 

DKPUT 

m 

INVALID  FILENAME 

34 

DKPUT 

Ll.LE.O  ON  UPDATE 

35 

DKPUT 

ABS(L2).LT.L1  ON  UPDATE 

36 

OKDEL 

LRID#0  FILE  DOES  NOT  EXIST  (RECORD  DELETE) 

37 

DKDEL 

INVALID  FILENAME 

38 

DKDEL 

PROTECTED  FILE 

39 

*  OKDEL 

SHARED  OS 

40 

DKOPN 

OPTION  OUT  OF  RANGE 

41 

OKOPN 

• 

ILLEGAL  FILENAME 

42 

DKOPN 

• 

OFT  FULL 

43 

DKSOF 

m 

FD  FULL  NO  EXTEND  YET 

44 

DKOPN 

- 

PROTECTED  FILE 

45 

DKOPN 

- 

SHAPED  DS 

46 

OKFIL 

- 

ILLEGAL  FILENAME 

47 

DKGLS 

- 

ILLEGAL  FILENAME 

48 

DKRNM 

NEW  FILENAME  ALREADY  EXISTS 

58 

DKFIL 

CAN'T  GET  TO  D.HAND  TASK 

68 

UNUSE 

• 

0 

69 

UNUSE 

• 

D 

70 

DKGET 

m 

Ll.LT.O 

71 

DKGET 

- 

L2.LT.0 

72 

DKGET 

- 

Ll.GT.LRLEN 

73 

OKXBM 

BIT  MAP  IS  FULL.  CANNOT  BE  EXTENDED. 

74 

OKXDS 

- 

ALL  BLOCKS  IN  DATASET  USED. 

75 

LOCK/UNLOK  -  NRSRCS  NOT  POSITIVE. 

76 

DKADT 

- 

NO  ROOM  IN  DATASET  TABLE. 
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6  PROGRAM  CONVERSION 


The  data-handler  has  been  written  to  minimize  the  time  required 
to  convert  the  system  from  one  computer  to  another.  All  conversion 
instructions  are  given  as  comment  statements  within  the  code  of  the 
following  subroutines: 

DKBEX 
0KB  IN 
OKCOS 
DKDDF 
OKERR 
OKGOl 
DKJCL 
OKMVC 
OKNCS 
OKNOS 
OKNIT 
OKODS 
OKPAK 
OKRBL 
DKTRC 
OKUPK 
OKWAT 
OKWBL 
OKXDS 
SNAP 
TIMDAT 

The  programmer  performing  this  conversion  should  follow  the 
instructions  given  in  Appendix  C,  Several  subroutines  have  been 
written  in  IBM  BAL  to  improve  executive  speeds.  These  routines  must 
be  rewritten  if  the  data-handler  is  being  converted  for  use  on  com¬ 
puter  systems  other  than  the  IBM  360/370  series.  The  following  is  a 
list  of  the  applicable  routines: 

OKBEX 
0KB  IN 
DKDDF 
DKJCL 
OKMVC 
OKNCS 
OKPAK 
OKUPK 
TIMDAT 
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After  each  program  has  been  rewritten  in  the  new  assembly  lan¬ 
guage,  the  code  should  be  added  to  the  documentation  tapes  immedi¬ 
ately  after  the  previous  version.  The  previous  code  should  not  be 
removed  from  the  documentation  tapes.  This  documentation  system  will 
allow  the  data-handler  to  be  loaded  in  a  relatively  short  time  period 
onto  a  new  computer  system  that  is  using  a  previously  used  assembler 
with  minimal  resources. 
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7  DOCUMENTATION  TAPES 


The  documentation  tapes  provide  a  complete  historic  record  of 
all  computer  programs  ever  written  for  the  data-handler.  All  tapes 
are  unlabeled,  recorded  at  a  density  of  800  bits  per  inch  (BPI),  and 
blocked  800  characters  per  physical  record.  Each  logical  record  is 
80  characters  in  length. 

The  programs  are  listed  in  alphabetical  order.  Assembly  pro¬ 
grams  are  given  in  chronological  order.  The  computer  system  and 
operating  system  version  should  be  recorded  in  each  assembly  program 
in  the  first  few  comment  cards. 

All  assembly  programs  are  saved  to  allow  conversion  to  a  new 
computer  assembly  language  with  minimal  resource  expenditures.  Each 
program  is  written  as  a  separate  tape  file.  The  first  tape  file  con¬ 
tains  an  index  of  all  subsequent  files.  The  format  of  this  index  is 
shown  below: 
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DATA-HANDLER  TAPE  FILE  INDEX 


FILE 

NO. 


3—10 

Right 

Justified 


PROGRAM 

NAME 


13-20 

Left 

Justifi  ed 


SOURCE 

LANGUAGE 

23-40 

Left 

Justifi ed 


DATE 

WRITTEN 

43-50 

00/MM/YY 


DATE 

MODIFIED 

53—60 

DD/MM/YY 


UST 

Card  Columns 
Data  Form 


8  TEST  ROUTINE 


The  last  files  on  the  documentation  tapes  contain  a  test  routine 
that  checks  each  application  subroutine  field.  The  correct  results 
of  this  test  routine  are  given  on  the  tape  for  checking  purposes. 
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9  CHANGES  TO  OATA-HANDLER  PROGRAMS 


As  new  functions  are  implemented  into  the  data-handler,  the  fol¬ 
lowing  steps  should  be  rigidly  followed.  Execution  of  these  steps 
will  insure  that  the  changes  are  performed  correctly  and  documented 
comp! etely. 

STEP  ONE  -  Write  a  FORTRAN  program,  well  documented  with  comment 
statements.  Follow  the  standard  documentation  procedures  below.  If 
an  existing  program  is  being  changed,  change  the  FORTRAN  program 
before  changing  the  assembly  programs. 


Program  Name;  written  as  in  the  first  line  of  the  function  or  subroutine,  with 
arguments. 

Function:  brief  description  of  the  function  of  the  program.  ^ 

Author;  author's  name,  date  of  first  writing. 

Modifications:  author,  date  and  brief  description  of  the  reason  for  the 
change(s). 

Language;  programming  language. 

Calling  Sequence:  description  of  arguments  and  function  results. 

Routines  Called;  list  of  subroutines  and  functions  called  by  the  program. 

Tasks  or  Modules;  tasks  or  modules  containing  this  routine. 

Variables:  a  description  of  all  variables  used  in  the  program. 

COMMON  variables  will  generally  be  described  in  a  "main" 
program,  referenced  in  this  program.  The  structure  of 
.  arrays  and  meaning  of  variables  should  be  fully  described. 

Program  Logic:  A  detailed  description  of  the  algorithm(s)  used 

and  the  flow  of  the  program.  The  comments  generating 
this  portion  of  the  documentation  will  normally  be 
scattered  throughout  the  program  in  complete  English 
sentences. 

STEP  TWO  -  Change  the  last  date  modified  on  the  data-handler 

tape  y^lle  index. 

STp  THREE  -  Change  the  FORTRAN  compile  listing  on  the  documen- 

tation  tapes. 
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STEP  FOUR  -  (If  required)  -  Write  the  assembly  programs. 

STEP  FIVE  -  (If  required)  -  Change  the  last  date  modified  on  the 
data-handier  tape  file  index. 


STEP  SIX  -  (If  required)  -  Change  the  assembler  listing  on  the 
documentation  tapes. 


STEP  SEVEN  -  Change  the  test  routines  to  completely  test  the  new 
feature. 


STEP  EIGHT  -  Execute  the  entire  test  routine  package  and  replace 
the  results  on  the  documentation  tapes. 

STEP  NINE  -  Revise  this  report  as  required.  Document  all 
revisions  listed  for  this  document  at  the  beginning  of  the  report. 

STEP  TEN  -  Revise  all  application  programs  as  required  by  the 
change  in  the  data-handler. 
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APPENDIX  B :  SUBROUTINE  FUNCTION 
B.l  APPLICATION  PROGRAMS 


SUBROU- 
NUM-  TINE 


BER 

NAME 

1. 

DKDEL 

2. 

DKFIL 

3. 

DKGET 

4. 

OKINS 

5. 

DKLEN 

6. 

DKLOS 

7. 

DKNDS 

8. 

DKNIT 

9. 

DKOPN 

10. 

DKPUT 

11. 

DKRNM 

12. 

DKSET 

13. 

DKXIT 

FUNCTION 

ROUTINE  TO  DELETE  FILE  FILNM  (IF  RECID'O)  OR  LR  DECID  IF  NOT  0 
FILE  DOES  NOT  HAVE  TO  BE  OPEN  BUT  MUST  EXIST  FOR  RECORD  DELETE  FILE 
DELETE  OF  NON-EXISTENT  FILE  IS  NOT  AN  ERROR 

ROUTINE  SET  FSTAT  (COMMON)  TO  INDICATE  STATUS  OF  FILNM  (COMMON) 

GET  LOGICAL  RECORD  RECID  IN  DATA  SET  NDS  (COMMON) 

INSERT  LOGICAL  RECORD  INTO  DATA  SET  NDS  (COMMON)  IN  FILE  FILNM 
(COMMON)  AFTER  LR  RECID. 

ROUTINE  TO  GET  LENGTH  OF  LR  RECID  IN  DATA  SET  NDS  (COMMON) 

ROUTINE  TO  CLOSE  FILE  FILNM  (COMMON)  IN  DATA  SET  NDS  (COMMON) 

GIVEN  DATA  SET  NAME,  RETURN  DATA  SET  NUMBER 
INITIALIZES  ALL  DATA  HANDLER  VARIABLES 
OPEN  A  FILE  ROUTINE. 

PUT  LOGICAL  RECORD  INTO  DATA  SET  NDS  (COMMON)  IN  FILE  FILNM  (COM) 
ROUTINE  TO  RENAME  FILE 

ROUTINE  TO  RETURN  INFORMATION  ABOUT  DATA  SET  NDS 

ROUTINE  TO  LOOP  THRU  ALL  DATA  HANDLER  DATA  SETS  (NDA)  AND  CLOSE 
EM  DOWN 
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b.2  function  programs 


SUBROU¬ 

TINE 

NAME  FUNCTION 


DKABP  ADD  TO  BUFFER  PRIORITY:  CURRENTLY  KEEPS  AN  ORDERED  LIST  OF  BT 
ENTRIES  BY  MOST  RECENT  USE.  N  IS  IGNORED. 

DKALO  ROUTINE  TO  TURN  OFF  THE  PROTECT  BIT  FOR  FILE  FILNM  IN  DATA  SET 
NDS.  FILE  NEED  NOT  BE  OPEN 

DKARG  CHECK  VALIDITY  OF  NDS  AND  OPEN  DATA  SET  IF  NOT  ALREADY  OPEN 

DKASG  ROUTINE  TO  ALLOW  USER  TO  CONNECT  A  DATA  SET  NUMBER  NSW  TO  A 
PARTICULAR  LOGICAL  UNIT  NUMBERLUN  AND  FILE  NAME  FNAME. 

DKBEX  INTEGER  FUNCTION  TO  EXTRACT  NUMBR  BITS  FROM  SOURCE  WORD 

DKBIN  REAL  FUNCTION  TO  INSERT  THE  LOW-ORDER  NUMBR  BITS  FROM  ISOR 
INTO  RESLT  AND  RETURN  IN  REGISTER.  RESIT  IS  NOT  MODIFIED. 

DKCBL  ROUTINE  TO  COMPACT  A  BLOCK  AT  BUFFERIBTADD  CALCULATE  NUMBER  OF 
SU'S  TO  MOVE  FROM  POOL  SU  OTH  DISPL  I FROM  TO  POOL  SU  OTH 
DISPL  no  BY  SETTING  NO.  SU'S  IN  BLOCK  FROM  DST  AND  NO.  SU'-S 
FREE  im  OF  BLOCK  (IN  PR  HEADER)  MOVES  SU'S  ONE  AT  A  TIME 
WITH  UKPAK  AND  DKUPK  AND  UPDATES  SU'S  FREE  AT  END  OF  BLOCK. 
ASSUMES  IFROM.GE.ITO  EVENTUALLY  MUST  ALSO  MODIFY  FST 

DKCDS  OP  SYS  FILE  INTERFACE  ROUTINE  TO  CLOSE  A  DATA  SET 

DKDDl  GET  ALL  MACHINE  CHARS  IN  MACH  (1-13) 

DKDD2  DATA  SET' DUMP  ROUTINES 

DKOD3  DATA  SET  DUMP  ROUTINES 

DKDD4  NOT  WRITTEN 

DKDDF  ROUTINE  FOR  DYNAMIC  DEFINE  FILE  STATEMENT  IN  OS  FORTRAN  ISSUES 
OPEN  ON  DDNAME  FTNNFOOl 

OKDOS  DUMP  DATA  SET  ROUTINE  TO  PRODUCE  A  FORMAHED  DUMP  OF  DATA  SET 
NDS 

OKDLF  ROUTINE  TO  DELETE  ENTIRE  FILNM  (COMMON)  IN  DATA  SET  NDS  (COMMON) 

DKDL  RROUTINE  TO  DELETE  LR  (NSGNBL)  IN  FILE  FILNM  DATA  SET  NDS 

DKDMP  DATA  HANDLER 


SUBROU¬ 

TINE 

NAME  FUNCTION 


DKDSG  ROUTINE  TO  DELETE  THE  SEGMENT  WHOSE  LR  HEADER  IS  IN  H  IN  BUFFER 
IBTADO  ASSUMING  KBTPP  SET  BY  DKSTQ  (VIA  DKFND)  DOES  NOT  PRESENTLY 
COMPACT  THE  BLOCK  OR  MODIFY  FST 

DKEBF  ROUTINE  TO  EMPTY  THE  BUFFER  AT  IBTAD  WHOSE  HEADER  IS  IN  D  CHECKS 
FOR  PREVIOUS  I/O  COMPLETION  WRITES  AND  WAITS  IF  WRITTEN  INTO  AND 
ZERO  ENTRY  AND  D 

DKERR  CKECKS  ERROR  HANDLING  SWITCH  AND  EITHER  PRINTS  AND  ABORTS  OR 
RETURNS  WITHOUT  SAYING  ANYTHING 

DKFBF  FILL  BUFFER  ROUTINE:  BT  ENTRY  AT  IBTAD  IS  IN  D  GET  BLOCK  NBL  OF 
DATA  SET  NSW  IN  AND  WAIT  FOR  READ  COMPLETION 

DKFND  ROUTINE  TO  LOCATE  BLOCK  NBL  SEGMENT  NSG  OF  DATA  SET  NSW. 

SEARCHES  BT'S  FIRST'THEN  READS  INTO  CORE  RETURNS  IBTAD=THE  BT  ENTRY 
OISPL  WHERE  PR  IS  DOES  NOT  SET  MEMORY 

DKGBF  GET  A  BUFFER  ROUTINE:  CHOOSES  THE  NEXT  AVAILABLE  BUFFER  USING 

DKSBF  ROUTINE  SETS  ITS  PRIORITY  HIGH  WIHH  DKABP  AND  EMPTIES  IT  WITH 
DKEBF.  D  AND  BT  ENTRY  WILL  BE  ZEROED  AND  ALL  10  FINISHED  ON  RETURN. 

OKGBL  ROUTINE  TO  GET  A  BLOCS  FROM  FREE  SPACE  TABLE  OF  DATA  SET 

NDS  WORD  FROM  BIT  MAP  STORED  IN  DST  (IDSWD)  NUMBER  BST  (IDSWN) 

BITS  CORRESPOND  TO  BLOCKS  NUMBER  RT  TO  LEFT  IN  EACH  WORD  IF  DST 
(IDSWN)  »  0,  NO  WORD  THERE.  ALWAYS  ASSUME  WORD  MUT  BE  REPLD 
USES  INTERNAL  ARRAY  A  TO  STORE  DST  ENTRY 

DKGBM  ROUTINE  TO  GET  A  BIT  MAP  WORD  FOR  NS  WHICH  HAS  AT  LEAST  ONE 
BLOCK  AVAILABLE  (BIT=0)  WITHIN  THE  BLOCKS  INITIALIZED 

DKLGl  ROUTINE  TO  GET  THE  SEGMENT  OF  THE  LR  (NSWNSEGNBLK)  CONTAINING  NCS 
INTO  CORE  BUFFER  AND  SETS  D=BT  HEADER  H=LR  HEADER  SETS  QPPP  FOR 
BUFFER  CONTAINING  DESIRED  SEGMENT  ALSO  SETS  PREID  FOLID  AND  LRLEN  IN 
COMMON  FROM  EITHER  LAST  BT  MEMORY  IF  SEGMENT  FOUND  THERE  OR  FROM  FIR^ 
AND  LAST  BUFFER  EXCEPT  FOR  THE  LOOP  TO  GET  LAST  SEGMENT 

DKGLS  ROUTINE  TO  GET  LAST  SEGMENT  OF  LR  (NSGNBL)  IN  NDS 

DKGO  ROUTINE  TO  INITIALIZE  THE  DATA  HANDLER  BUILDS  NECESSARY  TABLES 

FROM  ARRAY  IN  BLANK  COMMON  STARTING  AT  WORD  ISTRT  FOR  ILEN  WORS  - 
ALSO  SETS  CONSTANTS  AND  INITIALIZES  VARIABLES 

DKGOl  SET  MACHINE  PARAMETERS  IFR  IBM  360/370  WITH  OS 


SUBROU- 
NUM  TINE 

•BER  NAME  FUNCTION 


DKIDS  ROUTINE  TO  INITIALIZE  THE  RECORDS  IN  A  NEW  DATA  SET  IN 
PARTICULAR  TO  SET  UP  BLOCK  1  WITH  TWO  SEGMENTS: 

DKJCL 

DKMFS  ROUTINE  TO  SEARCH  THE  FST  AND  LOCATE  THE  BLOCK  WITH  THE  MOST 
FREE  SPACE  WHICH  IS  RETURNED  IN  NBL. 

DKMIC  ROUTINE  TO  SEARCH  IN  CORE  BUFFER  TABLES  FOR  ONE  WITH  DATA  SET 
NDS  FILENAME  FILNM  AND  RETURN  THE  ONE  WITH  THE  MOST  FREE  SPACE. 

DKMIR  ROUTINE  FOR  BUFFER  MEMORY  ID  RESET  TO  ENSURE  THAT  WHEN  A  NEW 

LOGICAL  RECORD  (RID)  IS  ADDED  OR  INSERTED  THE  PRECEEDIN6  (NSGPNBLP) 
AND  FOLLOWING  (NSGFNBLF)  RECORDS  (IF  THEY  APPEAR  IN  ANY  BT  MEMORY) 
HAVE  THEIR  FOLID  AND  PREID  ENTRIES  RESPECTIVELY  EQUAL  RID. 

DKMLR  ROUTINE  FOR  MEMORY  LENGTH  RESET  IN  BT  ENTRIES 

DKMST  SETS  BUFFER  MEMORY  PARAMETERS  INTO  D 

.  DKNCS  ROUTINE  TO  COMPUTE  THE  NUMBER  OF  CHARACTERS  IN  A  LR  SEGMENTS 

DKNSG  ROUTINE  TO  GET  NEXT  SEGMENT  OF  THE  LR  WHOSE  HEADER  IS  IN  H  INTO 
A  BUFFER  SETS  BT  ADDR  IN  IBTAD  BT  ENTRY  IN  D. 

DKOUT  BRINGS  ACTIVITY  ON  THIS  DATA  SET  TO  AN  ORDERLY  HALT  CLOSE  ANY 

OPEN  DH  FILES  IN  THIS  DATA  SET  AND  WAIT  FOR  ANY  BUFFER  I/O  ACTIVITY. 

DKPAl  PUT  ADD  RECORD  BUFFERING  LOGIC  -  ACTION  1:  LR  WILL  ENTIRELY 
FIT  INTO  IN-CORE  BUFFER  AT  IBTADD 

DKPA2  PUT  ADD  RECORu  BUFFERING  LOGIC  -  ACTION  2:  LR  PLACED  IN  REMAINDER 
OF  THE  IN-CORE  BUFFER  AT  IBTADD  AND  THEN  IN  ONE  OR  MORE  NEW 
BLOCKS.  THIS  LATTER  IS  DONE  VIA  DKPA4. 

DKPA3  NOT  'WRITTEN  YET 

DKPA4  PUT  ADO  RECORD  BUFFERING  LOGIC  -  ACTION  4:  LR  MUST  BE  PLACED 
IN  ONE  OR  MORE  NEW  BLOCKS 

DKPA5  PROGRAM  NOT  WRITTEN  YET 

DKPAK  ROUTINE  TO  PLACE  !CT  WORDS  OF  D  (IN  SU'S,  NBU  BITS)  INTO  POOL 
ARRAY 

DKPAR  ROUTINE  TO  DETERMINE  THE  PUT  ADD  RECORD  BUFFERING  RULE 


SUBROU- 
NUM  TINE 

BER  NAME  FUNCTION 


DKPBL  PUT  BLOCK  NBL  BACK  IN  BIT  MAP  OF  DATA  SET  NDS  SO  IT  CAN  BE  REUSED 
DKPBM  ROUTINE  TO  REPLACE  THE  NTH  SU  (IN  WORD)  IN  THE  BIT  MAP  OF  NDS 

DKPMD(A)  ROUTINE  TO  UPDATE  THE  PTR  IN  THE  LRID  WRITTEN  PRIOR  TO  CURRENT 
ONE  IF  IN  CHAIN  MODE 

DKPRO  ROUTINE  TO  SET  PROTECT  BIT  FOR  FILE  FILNM  IN  DATA  SET  NDS 
DKPSG  PUT  LR  SEGMENT  ROUTINE  USED  TO  ADD  A  NEW  SEGMENT  AT  END  OF  BUF 
OKPSH  ROUTINE  TO  REPLACE  THE  LR  SEGMENT  HEADER  IN  H  INTO  BUFFER 
DKRBL  READS  BLOCK  NBL  FROM  DATA  SET  NSW  INTO  BT  ENTRY  IBTAD(IN  D) 

OKSBF  SELECT  BUFFER  ROUTINE 

DKSFD  SEARCH  FILE  DIRECTORY  ROUTINE  IN  DS  NSW 

DKSOF  SEARCH  OPEN  FILE  TABLE  ROUTINE  FOR  FILNM  (COMMON)  IN  DATA  SET  NDS 
(COMMON)  RETURNS  lOFAO: 

DKSTQ  ROUTINE  TO  LOOP  THRU  BT  ENTRY  IBTAD  AND  LOCATE  SEGMENT  NS6 

DKTLR  ROUTINE  TO  TRUNCATE  CURRENT  SEGMENT  AT  CHAR  NCE  COMPACT  THE 
BLOCK  AND  DELETE  ANY  FOLLOWING  SEGMENTS. 

DKTRC  ROUTINE  TO  PROVIDE  A  TRACEBACK  AND  OTHER  INFO  WHEN  ERROR  CALLED 
BY:  DKERR  IBM  OS  VERSION  H  LEVEL  OBJECT  TIME  SYSTEM 

DKUPK  ROUTINE  TO  PLACE  ICT  SU'S  OF  POOL  ARRAY  P  BEGINNING  AT  ISTRT+1 
INTO  D  (ONE  SU  PER  WORD) 

DKWAT  WAIT  ROUTINE:  WAITS  FOR  BIT  IBIT  TO  CLEAR  IF  SET  IN  BT  STATUS 
WORD.  ALLOWS  ASYNCHRONOUS  I/O  OPERATIONS  WITH  THE  PROPER  OP  SYS 
INTERFACE  SUPPORT  (DKRBL  AND  DKWBL). 

DKWBL  WRITES  BLOCK  NBL  FROM  BT  ENTRY  IBTAB(IN  D)  INTO  DATA  SET  NSW 

DKWIN  ROUTINE  TO  SET  THE  'WRITTEN  INTO'  BIT  IN  BT  ENTRY  IN  D 
DOES  NOT  REPLACE  D 

DKXBM  ROUTINE  TO  EXTEND  BIT  MAP  BY  ONE  SEGMENT 
DKXDS  ROUTINE  TO  EXTEND  DATA  SET 


^0 


SUBROU- 
NUM  TINE 

8ER  NAME  FUNCTION 


DKXFO  EXTEND  FILE  DIRECTORY  OF  DATA  SET  NDS  (COMMON)  BY  ONE  BLOCK 

•  DKXLR  ROUTINE  TO  EXTEND  THE  LR  (NSGNBL)  WHOSE  LAST  SEGMENT  IS  IN  BT 
ENTRY  IBTAD.D  AND  WHOSE  LR  HEADER  IS  IN  HEDLR 

XOR 

DKOOS  OPEN  DATA  SET  TO  HOST  OP  SYSTEMS  FILE  CONTROL  SERVICES 

OKOMP  DUMPS  DATA  HANDLER  COMMON  AND  POOL  THIS  ROUTINE  IS  A  FUNCTION  OF 
MACHINE  CHARACTERISTICS  SUCH  AS  CHARS  PER  WORD  AND  CHARS  IN  A  DATA 
SET  NAME 

G0T236  THIS  ROUTINE  IS  ENTERED  BY  THE  FORTRAN  EXTENDED  ERROR  HANDLING 
ROUTINES 

BITEX  RIGHT  JUSTIFY  THE  BITS  TO  BE  RETURNED 

BITIN  THE  RIGHTMOST  NUMBR  BITS  OF  SOURC  ARE  INSERTED  INTO  RESLT 

BEGINNING  WITH  BIT  START  OF  RESLT.  THE  REMAINING  BITS  OF  RESLT 
ARE  NOT  MODIFIED 


ICOPY  COPIES  NUM  CHARACTERS  FROM  SOURC  (STARTING  AT  SFST)  TO  DEST 

(STARTING  WITH  DFST)  ALL  OTHER  CHARACTERS  OF  DEST  ARE  UNCHANGED 

PACK  PACK  NUM  CHARACTERS  INTO  THE  STRING  DEST  STARTING  WITH  CHARACTER 
L2  OF  DEST.  THE  CHARACTERS  ARE  TAKEN  FROM  THE  LEAST  SIGNIFICANT 
CHARACTER  OF  THE  ELEMENTS  OF  THE  ARRAY  SOURC  STARTING  WITH 
STANDARD  UNIT  LI. 

SNAP 

SYSCM  INITIALIZE  SYSTEM  COMMON  TO  THE  STANDARD  VALUES  REQUIRED  BY  THE 
PARTICULAR  MACHINE  IMPLEMENTATION 


DKMVC  MOVE  NC  CHARACTERS  TO  A(TO)+ITOFF 
DKBNF  ROUTINE  TO  INSERT  AN  INTEGER  FORTRAN  WORD  INTO  A  REAL 
FORTRAN  WORD 

DKBXF  ROUTINE  TO  EXTRACT  AN  INTEGER  FORTRAN  WORD  FROM  A  REAL 
FORTRAN  WORD. 

AND 

DKCMP 


SUBROU- 
NUM  TINE 

BER  NAME  FUNCTION 


OR 

SHIFT 


TIMDAT 


